Introduction

The metric (represented by the SparkplugMetric Class) is the central object in Sparkplug edge node or device. Depending on the purpose of the metric, it provides means to publish data and/or receive commands. It has properties that influence its behavior, such as the metric data type.

When you develop an edge node using Rapid Toolkit for Sparkplug, you need to define the metrics of the edge node and its devices. In addition, the properties and behavior of each metric need to be defined as well. This is called the configuration of the metric. You can always configure your metrics by setting the various individual properties of the SparkplugMetric Class instance, and optionally hooking handlers to its events. The metrics in typical edge nodes are, however, usually configured in certain common ways. The Rapid Toolkit for Sparkplug provides extension methods that allow easier configuration of such typical metrics.

The extension methods for metric configuration are located in the SparkplugMetricExtension Class. The allow for fluent configuration, i.e. each method returns the reference to the metric it is operating on, and the method calls can therefore be chained.

Some metric configuration methods exist in multiple overloads. Such methods have the same purpose, but allow different combinations of how the arguments are specified, and their defaults. In some cases, a method overload exists that has generic type parameter which typically corresponds to the type the metric will have. In such case, the method overload can determine the Sparkplug data type from this generic type parameter. In addition, in many cases you do not even have to specify it, because it can be inferred from the code by the compiler. For example, if you pass "read value function" (a function that implements the reading of metric's value) that returns a String to the metric configuration method, the method will determine that the Sparkplug type of the metric will also be a (scalar) String. For more complicated cases, other method overloads then allow you to specify the Sparkplug data type and other parameters explicitly using method arguments.

The configuration methods can be categorized as either "primitive" (they typically modify just one or two members of the metric) or "composite" (for more complete or full configuration of the metric). We will start with discussion of the primitive configuration methods, because it is good for understanding of how the things are put together; however, your code will probably mainly use the composite configuration methods, because using them gives short and clear code. 

For information related to configuration of the data type, see Sparkplug Metric Data Type Considerations.

Primitive Configuration Methods

The primitive configuration methods modify only one member of the metric, or a closely tight group of members. You will normally use more of the primitive configuration methods together, in order to achieve the configuration that you want. Also, primitive configuration methods can sometimes be used to "post-configure" (i.e. further modify) the metric that has been configured using the composite methods (described further below).

Whenever you can, look for a composite configuration method to configure the metric according to your needs - and you will usually find it. Only if there is no composite configuration method that can be used, use the primitive configuration methods.

The following table lists the primitive configuration methods available and their purpose. The table also indicates which properties or events of the metric are affected and how.  

Method or Group of Method Overloads	Description	DataType Property	PropagateRead Property	PropagateWrite Property	Read Event	IsReadable Property	ReadData Property	IsWritable Property, WritableTimestamp Property	Write Event	WriteData Property	WriteLoopback Property
ProcessRead Method	Specifies that reads of this metric will be processed by the specified read function.	⨯	⨯	⨯	✓	⨯	⨯	⨯	⨯	⨯	⨯
ProcessWrite Method	Specifies that writes of this metric will be processed by the specified write function.	⨯	⨯	⨯	⨯	⨯	⨯	⨯	✓	⨯	⨯
Readable Methods	Modifies the metric to be readable or not.	⨯	⨯	⨯	⨯	✓	⨯	⨯	⨯	⨯	⨯
ValueType Methods	Makes the metric to use the specified value type.	✓	⨯	⨯	⨯	⨯	✓ (optionally)	⨯	⨯	✓ (optionally)	⨯
Writable Methods	Modifies the metric to be writable or not, also allowing to specify whether its timestamp will be writable.	⨯	⨯	⨯	⨯	⨯	⨯	✓	⨯	⨯	⨯

In order to make a read-only metric (prevent commands processing by the metric, only allow publishing of metric data), call the Writable Method with its argument set to false.

In order to make a write-only metric (prevent publishing of metric data, only allow commands be sent to it), call the Readable Method with its argument set to false.

There is also the SetState Method, which allows you to modify the State Property of any node. You can use this method to set the state object in the metric to any reference (object) that has relation to the metric in your project. This way, you can associate your own objects with the metrics.

Composite Configuration Methods

The composite configuration methods are build on top of the primitive configuration methods. They provide a way to define the most common metric behaviors without having to bother with setting multiple properties and/or hooking to event of the metric object.

Methods exist for 4 distinct types of metric behavior:

• Constant data: Use Constant Methods or ConstantValue Methods.
• Read-write register: Use ReadWrite Methods or ReadWriteValue Methods.
• Read pull: You specify a code that performs the Read. Use ReadFunction Methods or ReadValueFunction Methods.
• Write push: You specify a code that performs the Write. Use WriteFunction Methods, WriteValueAction Methods, or WriteValueFunction Methods.

The methods operate on the metric itself, and assume that the behavior of each metric will be defined separately. In some edge nodes or devices, it is beneficial to define the same behavior for a specific sub-set of data variables, on the parent level (edge node or device). In such cases you need to hook events or override methods on the parent object, and the composite configuration methods described here are not suitable for this task.

The methods that have "Value" in their name allow you to work simply with the Value part of the metric's data, whereas the method without the "Value" in their operate on the whole SparkplugData Class instance, i.e. also including the timestamp.

In many cases, a call to a single composite configuration method with appropriate parameters is enough to fully configure the metric. Two method calls are needed if you want to define the code for both "read pull" and "write push". In some cases, a call to a composite configuration methods might be followed by a call to some primitive configuration methods, to "fine-tune" certain metric properties.

The following table lists the composite configuration methods available and their purpose. The table also indicates which properties or events of the metric are affected and how.

Method or Group of Method Overloads	Description	DataType Property	PropagateRead Property	PropagateWrite Property	Read Event	IsReadable Property	ReadData Property	IsWritable Property, WritableTimestamp Property	Write Event	WriteData Property	WriteLoopback Property
Constant Methods	Modifies the metric to provide the specified constant metric data (value, timestamp), non-writable.	✓	false	⨯	⨯	true	✓	false, false	⨯	⨯	⨯
ConstantValue Methods	Modifies the metric to provide the specified constant value, non-writable.	✓	false	⨯	⨯	true	✓	false, false	⨯	⨯	⨯
ReadFunction Methods	Modifies the metric to provide metric data for the pull data provision model by a specified function.	✓	⨯	⨯	✓	true	⨯	⨯	⨯	⨯	⨯
ReadValueFunction Methods	Modifies the metric to provide value for the pull data provision model by a specified function.	✓	⨯	⨯	✓	true	⨯	⨯	⨯	⨯	⨯
ReadWrite Methods	Modifies the metric to behave as read-write register, with specified initial metric data (value, timestamp).	✓	false	false	⨯	true	✓	true, true	⨯	✓	true
ReadWriteValue Methods	Modifies the metric to behave as read-write register, with specified initial value.	✓	false	false	⨯	true	✓	true, false	⨯	✓	true
WriteFunction Methods	Modifies the metric for consuming metric data by a specified function, for the push data consumption model.	✓	⨯	⨯	⨯	⨯	⨯	true, true	✓	⨯	⨯
WriteValueAction Methods	Modifies the metric for consuming values by a specified action, for the push data consumption model.	✓	⨯	⨯	⨯	⨯	⨯	true, false	✓	⨯	⨯
WriteValueFunction Methods	Modifies the metric for consuming values by a specified function, for the push data consumption model.	✓	⨯	⨯	⨯	⨯	⨯	true, false	✓	⨯	⨯

 

Constant Methods

The Constant methods modify the metric to provide the specified constant metric data (value, timestamp), non-writable.

The metric is made read-only. The metric will provide always the same metric data, specified in this method call.

If your constant data should take the current time as the timestamp, you can use the ConstantValue method instead. 

ConstantValue Methods

The ConstantValue methods modify the metric to provide the specified constant value, non-writable.

The metric is made read-only. The metric will provide always the same value, specified in this method call. The timestamp will be the current time of this method call.

If you need a different timestamp, use the Constant method instead.

Example: Examples - Sparkplug Edge Node - Create metric with a constant value

ProcessRead Method

The ProcessRead method specifies that reads of this metric will be processed by the specified read function.

This method works by adding an event handler to the Read Event event of the metric.

ProcessWrite Method

The ProcessWrite method specifies that writes of this metric will be processed by the specified write function.

This method works by adding an event handler to the Write Event event of the metric.

Readable Methods

The Readable methods modify the metric to be readable or not.

In order to configure the metric, you will typically combine this method with more configuration methods.

Example: Examples - Sparkplug Edge Node - Implement a write-only metric using an action

ReadFunction Methods

The ReadFunction methods modify the metric to provide metric data for the Rapid Toolkit for Sparkplug Pull Data Provision Model by a specified function.

If the collected data should always take the current time as the timestamp, you can use the ReadValueFunction method instead.

Example: Examples - Sparkplug Edge Node - Implement reading using a function

ReadValueFunction Methods

The ReadValueFunction methods modify the metric to provide value for the Rapid Toolkit for Sparkplug Pull Data Provision Model by a specified function.

If you do not want to use the current time as the timestamp, use the ReadFunction method instead.

Example: Examples - Sparkplug Edge Node - Implement reading a value using a function

ReadWrite Methods

The ReadWrite methods modify the metric to behave as read-write register, with specified initial metric data (value, timestamp).

This method makes the metric both readable and writable. The data written to the metric will become the data subsequently published by the metric.

This method also makes the timestamp of the metric writable, i.e. Sparkplug host applications will be able to modify the timestamp. If you need a different behavior, call the Writable method subsequently, with desired parameters.

If you want a register that does not have a writable timestamp, you can use the ReadWriteValue method instead. 

Example: Examples - Sparkplug Edge Node - Implement a register that allows writing a timestamp

ReadWriteValue Methods

The ReadWriteValue methods modify the metric to behave as read-write register, with specified initial value.

Example: Examples - Sparkplug Edge Node - Implement a register with initial value

ValueType Methods

The ValueType methods make the metric to use the specified value type. The methods also initialize the metric data (i.e. the ReadData Property and the WriteData Property) with a default value for the given data type (otherwise the initial value is null), except when you use an overload that allows to suppress such initialization by a boolean argument.

In order to configure the metric, you will typically combine this method with more configuration methods.

Example: Examples - Sparkplug Edge Node - Update read value in push data provision model

Example: Examples - Sparkplug Edge Node - Reading different metrics by a single handler

Writable Methods

The Writable methods modify the metric to be writable or not, also allowing to specify whether its timestamp will be writable.

In order to configure the metric, you will typically combine this method with more configuration methods.

Example: Examples - Sparkplug Edge Node - Implement a register that allows writing a timestamp

WriteFunction Methods

The WriteFunction methods modify the metric for consuming metric data by a specified function, for the Rapid Toolkit for Sparkplug Push Data Consumption Model.

The write function accepts the metric data (an instance of SparkplugData Class), and returns a success indication (a boolean) that indicates the outcome of the Sparkplug write. The WriteFunction methods are the most generic extension methods for writing. If you only need to deal with metric value (and not its timestamp), consider using one of the WriteValueFunction or WriteValueAction method overloads, for shorter code and easier programming.

Example: Examples - Sparkplug Edge Node - Implement data writing using a function

WriteValueAction Methods

The WriteValueAction methods modify the metric for consuming values by a specified action, for the Rapid Toolkit for Sparkplug Push Data Consumption Model.

A successful outcome of the Sparkplug write operation is always assumed. If you ever want to fail the Sparkplug write operation, use one of the WriteValueFunction method overloads instead. With these methods, you specify a write value function that returns a boolean success indication that is the Sparkplug write operation outcome.

Example: Examples - Sparkplug Edge Node - Implement a write-only metric using an action

WriteValueFunction Methods

The WriteValueFunction methods modify the metric for consuming values by a specified function, for the Rapid Toolkit for Sparkplug Push Data Consumption Model.

The write function returns a boolean that indicates the outcome of the Sparkplug write operation. If your write operation is always successful, you can make your code a bit simpler by using one of WriteValueAction method overloads instead.

Example: Examples - Sparkplug Edge Node - Implement value writing using a function

 

Sparkplug is a trademark of Eclipse Foundation, Inc. "MQTT" is a trademark of the OASIS Open standards consortium. Other related terms are trademarks of their respective owners. Any use of these terms on this site is for descriptive purposes only and does not imply any sponsorship, endorsement or affiliation.